/* 
 * Recursive inclusion prevention mechanism for unit utilities header file
 * Standard C preprocessor technique to prevent multiple header inclusions
 * Ensures utility function declarations are processed only once per compilation unit
 * Maintains compilation efficiency and prevents symbol redefinition conflicts
 */
/* Define to prevent recursive inclusion -------------------------------------*/
#ifndef __UNIT_H
#define __UNIT_H

/* 
 * Standard integer type definitions inclusion
 * Provides platform-independent fixed-width integer types like uint8_t, uint64_t
 * Ensures consistent data type sizes across different hardware architectures
 * Essential for portable code and predictable memory usage in utility functions
 */
#include <stdint.h>

/* 
 * External function declarations for general-purpose utility operations
 * These functions provide common services used across multiple application modules
 * Include token generation, application state management, timing, and data conversion
 * Designed as reusable components to promote code modularity and maintainability
 */

/**
 * @brief Generate unique sequential token for message identification
 * 
 * This function creates incrementing token values used for message correlation and tracking
 * Implements wrap-around logic to prevent token value overflow at maximum range
 * Tokens are used to match requests with corresponding responses in communication protocols
 * Provides thread-safe token generation through atomic seed increment operation
 * 
 * @param token Character buffer to store the generated token string representation
 */
extern void get_token(char *token);

/* 
 * Query current application running status
 * This function returns the operational state of the main application process
 * Used by monitoring systems and dependent modules to determine application availability
 * Provides thread-safe status checking for coordinated system operation management
 * 
 * @return uint8_t Current application running status (SET = running, RESET = stopped)
 */
extern uint8_t is_app_running(void);

/* 
 * Update application running status flag
 * This function modifies the global application state indicator during lifecycle transitions
 * Used during application startup, shutdown, and state change operations
 * Supports coordinated state management across multiple application components
 * 
 * @param running New running status value to set (SET or RESET constants)
 */
extern void set_app_running(uint8_t running);

/* 
 * Implement millisecond precision delay using system select call
 * This function provides accurate timing delays superior to standard sleep functions
 * Uses select system call with timeout for precise sub-second timing control
 * Handles signal interruptions gracefully with automatic retry mechanism
 * Essential for polling loops, timing-sensitive operations, and rate limiting
 * 
 * @param mSec Number of milliseconds to suspend execution (0 to 4,294,967,295)
 */
extern void delay_ms(unsigned long mSec);

/* 
 * Generate ISO 8601 formatted timestamp string from system time
 * This function retrieves current system time and formats it as standardized timestamp
 * Creates human-readable timestamp in YYYY-MM-DDTHH:MM:SS format for logging and messaging
 * Supports temporal correlation of events across distributed system components
 * Provides consistent time formatting independent of locale settings
 * 
 * @param psDateTime Pre-allocated character buffer to receive formatted timestamp string
 */
extern void mqtt_get_time(char *psDateTime);

/* 
 * Convert ASCII hexadecimal string to binary byte array
 * This function parses hexadecimal character strings into raw binary data representation
 * Supports both uppercase and lowercase hexadecimal digits (A-F, a-f, 0-9)
 * Handles input strings of even or odd length with proper nibble alignment
 * Used for protocol data conversion, configuration parsing, and binary payload processing
 * 
 * @param str Input string containing hexadecimal ASCII characters to convert
 * @param out Output buffer to receive converted binary data bytes
 * @return int Number of bytes successfully converted and stored in output buffer
 */
extern int AtoH(char *str, uint8_t *out);

/* 
 * Convert integer value to Binary Coded Decimal (BCD) format
 * This function transforms 8-bit integer values into BCD representation
 * Separates tens and units digits into high and low nibbles of single byte
 * Used for numerical data encoding in communication protocols and display systems
 * Supports input values from 0 to 99 with proper digit separation
 * 
 * @param data Integer value to convert to BCD format (0-99 range supported)
 * @return uint8_t BCD encoded value with tens digit in high nibble, units in low nibble
 */
extern uint8_t itobcd(uint8_t data);

/* 
 * High-resolution system time retrieval in microseconds
 * This function provides microsecond-precision timing using system clock facilities
 * Combines seconds and microseconds components into single 64-bit value
 * Used for performance measurements, timeout calculations, and precise event timing
 * Supports long-duration timing operations with 64-bit range protection
 * 
 * @return uint64_t Current system time in microseconds since epoch
 */
extern uint64_t get_system_time_us(void);

/* 
 * Calculate absolute time difference between two microsecond timestamps
 * This function computes elapsed time between two timing points with wrap-around protection
 * Handles 64-bit timer overflow correctly by calculating remaining time space
 * Provides reliable time interval measurements for long-running processes and monitoring
 * Essential for timeout detection, performance profiling, and interval-based operations
 * 
 * @param current Later timestamp in microseconds for difference calculation
 * @param last Earlier timestamp in microseconds for difference baseline
 * @return uint64_t Absolute time difference in microseconds, handling timer wrap-around
 */
extern uint64_t get_system_time_absoffset(uint64_t current, uint64_t last);

/* 
 * End of unit utilities header file inclusion protection
 * Closes the #ifndef __UNIT_H preprocessor conditional block
 * Completes the recursive inclusion prevention mechanism for utilities header
 */
#endif /* __UNIT_H */